home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3p / usmalloc.z / usmalloc
Encoding:
Text File  |  2002-10-03  |  8.9 KB  |  133 lines
  1.  
  2.  
  3.  
  4. UUUUSSSSMMMMAAAALLLLLLLLOOOOCCCC((((3333PPPP))))                                                      UUUUSSSSMMMMAAAALLLLLLLLOOOOCCCC((((3333PPPP))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      uuuussssmmmmaaaalllllllloooocccc,,,, uuuussssffffrrrreeeeeeee,,,, uuuussssrrrreeeeaaaalllllllloooocccc,,,, uuuussssccccaaaalllllllloooocccc,,,, uuuussssmmmmaaaalllllllloooopppptttt,,,, uuuussssmmmmaaaalllllllliiiinnnnffffoooo,,,, - shared
  10.      arena memory allocator
  11.  
  12. CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<uuuulllloooocccckkkkssss....hhhh>>>>
  14.      ####iiiinnnncccclllluuuuddddeeee <<<<mmmmaaaalllllllloooocccc....hhhh>>>>
  15.  
  16.      vvvvooooiiiidddd ****uuuussssmmmmaaaalllllllloooocccc ((((ssssiiiizzzzeeee____tttt ssssiiiizzzzeeee,,,, uuuussssppppttttrrrr____tttt ****hhhhaaaannnnddddlllleeee))));;;;
  17.  
  18.      vvvvooooiiiidddd uuuussssffffrrrreeeeeeee ((((vvvvooooiiiidddd ****ppppttttrrrr,,,, uuuussssppppttttrrrr____tttt ****hhhhaaaannnnddddlllleeee))));;;;
  19.  
  20.      vvvvooooiiiidddd ****uuuussssrrrreeeeaaaalllllllloooocccc ((((vvvvooooiiiidddd ****ppppttttrrrr,,,, ssssiiiizzzzeeee____tttt ssssiiiizzzzeeee,,,, uuuussssppppttttrrrr____tttt ****hhhhaaaannnnddddlllleeee))));;;;
  21.  
  22.      vvvvooooiiiidddd ****uuuussssccccaaaalllllllloooocccc ((((ssssiiiizzzzeeee____tttt nnnneeeelllleeeemmmm,,,, ssssiiiizzzzeeee____tttt eeeellllssssiiiizzzzeeee,,,, uuuussssppppttttrrrr____tttt ****hhhhaaaannnnddddlllleeee))));;;;
  23.  
  24.      iiiinnnntttt uuuussssmmmmaaaalllllllloooopppptttt ((((iiiinnnntttt ccccmmmmdddd,,,, iiiinnnntttt vvvvaaaalllluuuueeee,,,, uuuussssppppttttrrrr____tttt ****hhhhaaaannnnddddlllleeee))));;;;
  25.  
  26.      ssssttttrrrruuuucccctttt mmmmaaaalllllllliiiinnnnffffoooo uuuussssmmmmaaaalllllllliiiinnnnffffoooo ((((uuuussssppppttttrrrr____tttt ****hhhhaaaannnnddddlllleeee))));;;;
  27.  
  28.      ssssiiiizzzzeeee____tttt uuuussssmmmmaaaallllllllooooccccbbbbllllkkkkssssiiiizzzzeeee ((((vvvvooooiiiidddd ****ppppttttrrrr,,,, uuuussssppppttttrrrr____tttt ****hhhhaaaannnnddddlllleeee))));;;;
  29.  
  30.      vvvvooooiiiidddd ****uuuussssrrrreeeeccccaaaalllllllloooocccc ((((vvvvooooiiiidddd ****ppppttttrrrr,,,, ssssiiiizzzzeeee____tttt nnnneeeelllleeeemmmm,,,, ssssiiiizzzzeeee____tttt eeeellllssssiiiizzzzeeee,,,,
  31.                     uuuussssppppttttrrrr____tttt ****hhhhaaaannnnddddlllleeee))));;;;
  32.  
  33.      vvvvooooiiiidddd ****uuuussssmmmmeeeemmmmaaaalllliiiiggggnnnn ((((ssssiiiizzzzeeee____tttt aaaalllliiiiggggnnnn,,,, ssssiiiizzzzeeee____tttt ssssiiiizzzzeeee,,,, uuuussssppppttttrrrr____tttt ****hhhhaaaannnnddddlllleeee))));;;;
  34.  
  35. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  36.      These routines provide a simple general-purpose memory allocation package
  37.      that allows the user to allocate from a shared arena (see _u_s_i_n_i_t(3P)).
  38.      All these functions are MP safe, multiple threads/processes may access
  39.      them simultaneously and are guaranteed correct behavior.
  40.  
  41.      More than one call can be made to _u_s_i_n_i_t(3P) to set up separate malloc
  42.      arenas.  The file name passed to _u_s_i_n_i_t(3P) is used as a key to allow
  43.      shared arenas to be created for use amongst unrelated processes.  Once
  44.      the arena is set up, calls to _u_s_m_a_l_l_o_c will attempt to allocate space
  45.      from the arena.  If the arena gets full, NNNNUUUULLLLLLLL is returned.  Note that
  46.      this malloc arena is also used by other _u_s* calls (such as _u_s_n_e_w_l_o_c_k and
  47.      _u_s_n_e_w_s_e_m_a ).
  48.  
  49.      The argument to _u_s_f_r_e_e is a pointer to a block previously allocated by
  50.      _u_s_m_a_l_l_o_c; after _u_s_f_r_e_e is performed this space is made available for
  51.      further allocation.
  52.  
  53.      Undefined results will occur if the space assigned by _u_s_m_a_l_l_o_c is overrun
  54.      or if some random number is handed to _u_s_f_r_e_e.  It is always permitted to
  55.      pass NULL to _u_s_f_r_e_e.
  56.  
  57.      _u_s_r_e_a_l_l_o_c changes the size of the block pointed to by _p_t_r to _s_i_z_e bytes
  58.      and returns a pointer to the (possibly moved) block.  The contents will
  59.      be unchanged up to the lesser of the new and old sizes.  If no free block
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. UUUUSSSSMMMMAAAALLLLLLLLOOOOCCCC((((3333PPPP))))                                                      UUUUSSSSMMMMAAAALLLLLLLLOOOOCCCC((((3333PPPP))))
  71.  
  72.  
  73.  
  74.      of _s_i_z_e bytes is available in the storage arena, then _u_s_r_e_a_l_l_o_c will ask
  75.      _u_s_m_a_l_l_o_c to enlarge the arena by _s_i_z_e bytes and will then move the data
  76.      to the new space.  In the special case of a null _p_t_r, _u_s_r_e_a_l_l_o_c
  77.      degenerates to _u_s_m_a_l_l_o_c.  A zero _s_i_z_e causes the passed block to be
  78.      freed.
  79.  
  80.      _u_s_c_a_l_l_o_c allocates space for an array of _n_e_l_e_m elements of size _e_l_s_i_z_e.
  81.      The space is initialized to zeros.
  82.  
  83.      _u_s_r_e_c_a_l_l_o_c combines _u_s_r_e_a_l_l_o_c and _u_s_c_a_l_l_o_c.  If the size of the block
  84.      increases, any new bytes are initialized to zero.  Note that for this to
  85.      work properly, all allocations of a given pointer must go through
  86.      _u_s_r_e_c_a_l_l_o_c.  If the original pointer was allocated with either _u_s_m_a_l_l_o_c
  87.      or _u_s_r_e_a_l_l_o_c some new bytes may not be set properly to zero.
  88.  
  89.      _u_s_m_e_m_a_l_i_g_n allocates _s_i_z_e bytes on a specified alignment boundary, and
  90.      returns a pointer to the allocated block.  The value of the returned
  91.      address is guaranteed to be an even multiple of _a_l_i_g_n.  Note: the value
  92.      of _a_l_i_g_n must be a power of two, and must be greater than or equal to the
  93.      size of a word, or, for 64 bit objects, the size of a doubleword.
  94.  
  95.      _u_s_m_a_l_l_o_c_b_l_k_s_i_z_e returns the actual size of the block pointed to by _p_t_r.
  96.      The returned size may be greater than the original requested size due to
  97.      padding and alignment.
  98.  
  99.      _u_s_m_a_l_l_o_p_t provides for control over the allocation algorithm.  See
  100.      _a_m_a_l_l_o_c(3P) for details on the allowable options.
  101.  
  102.      _u_s_m_a_l_l_i_n_f_o provides instrumentation describing space usage.  See
  103.      _a_m_a_l_l_o_c(3P) for details on the returned information.
  104.  
  105. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  106.      intro(3), usinit(3P), usconfig(3P), amalloc(3P), malloc(3X).
  107.  
  108. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  109.      _u_s_m_a_l_l_o_c, _u_s_c_a_l_l_o_c, _u_s_r_e_c_a_l_l_o_c, and _u_s_r_e_a_l_l_o_c return a NNNNUUUULLLLLLLL pointer if
  110.      there is no available memory or if the arena has been detectably
  111.      corrupted by storing outside the bounds of a block.  If _u_s_m_a_l_l_o_p_t is
  112.      called after any allocation (for most _c_m_d arguments) or if _c_m_d or _v_a_l_u_e
  113.      are invalid, non-zero is returned.  Otherwise, it returns zero.
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.